@arkyc/core 1.1.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toneflix Technologies Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/decision.d.mts

@@ -24,11 +24,30 @@ interface DecisionFaceMatchInput {
   /** Similarity between document portrait and selfie in [0, 1]. */
   similarityScore: number;
 }
+/** Address-verification signals fed to the decision engine. */
+interface DecisionAddressInput {
+  passed: boolean;
+  /** Overall address-verification confidence in [0, 1]. */
+  score: number;
+  /**
+   * What a failed result does: flag for `review` (default) or `reject`, driven
+   * by the workflow's address config. A low-confidence (but not failed) result
+   * is always review, never a reject.
+   */
+  onFail?: 'review' | 'reject';
+  /**
+   * Workflow-configured minimum confidence to auto-verify the address. A passed
+   * address scoring below this routes to manual review. Falls back to the
+   * project `addressThreshold` when omitted.
+   */
+  threshold?: number;
+}
 /** The complete set of signals the decision engine evaluates. */
 interface DecisionInput {
   document: DecisionDocumentInput;
   liveness: DecisionLivenessInput;
   faceMatch: DecisionFaceMatchInput;
+  address: DecisionAddressInput;
 }
 /** The decision engine's verdict for a session. */
 interface DecisionResult {
@@ -57,5 +76,5 @@ declare class DecisionEngine {
   static decide(input: DecisionInput, thresholds?: Partial<VerificationThresholds>): DecisionResult;
 }
 //#endregion
-export { DecisionDocumentInput, DecisionEngine, DecisionFaceMatchInput, DecisionInput, DecisionLivenessInput, DecisionResult };
+export { DecisionAddressInput, DecisionDocumentInput, DecisionEngine, DecisionFaceMatchInput, DecisionInput, DecisionLivenessInput, DecisionResult };
 //# sourceMappingURL=decision.d.mts.map

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,aAAA;EACf,QAAA,EAAU,qBAAA;EACV,QAAA,EAAU,qBAAA;EACV,SAAA,EAAW,sBAAA;AAAA;;UAII,cAAA;EACf,QAAA,EAAU,oBAAA;EACV,MAAA,EAAQ,cAAc;EARtB;EAUA,SAAA;AAAA;;cAIW,cAAA;EAZA;;AAAsB;AAInC;;;;;;;;;;AAIW;AAIX;EAZa,OA4BJ,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":";;;;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"}

package/dist/decision.mjs

@@ -29,11 +29,14 @@ var DecisionEngine = class {
 		if (input.document.expired) return verdict("rejected", "DOCUMENT_EXPIRED");
 		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");
 		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");
 		if (input.liveness.score < t.livenessThreshold) return verdict("requires_review", "LIVENESS_LOW_CONFIDENCE");
 		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");
 		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/** The complete set of signals the decision engine evaluates. */\nexport interface DecisionInput {\n  document: DecisionDocumentInput\n  liveness: DecisionLivenessInput\n  faceMatch: DecisionFaceMatchInput\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\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\n    // --- All checks cleared ---\n    return verdict('approved', 'AUTO_APPROVED')\n  }\n}\n"],"mappings":";;;;AA+CA,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,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;EAI/D,OAAO,QAAQ,YAAY,eAAe;CAC5C;AACF"}
+{"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"}

package/dist/index.d.mts

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

package/dist/normalize.d.mts

@@ -1,15 +1,20 @@
 import { DecisionInput } from "./decision.mjs";
-import { FaceMatchResultData, IsoDateTime, LivenessResultData, OcrResultData, WebhookChecks } from "@arkyc/types";
+import { AddressOnFail, AddressResultData, FaceMatchResultData, IsoDateTime, LivenessResultData, OcrResultData, WebhookChecks } from "@arkyc/types";
 
 //#region src/normalize.d.ts
 /**
  * The raw provider outputs gathered for a session, plus the document quality.
+ * `address` is only present when the (opt-in) address stage ran.
  */
 interface SessionSignals {
   documentQualityScore: number;
   ocr: OcrResultData;
   liveness: LivenessResultData;
   faceMatch: FaceMatchResultData;
+  /** Address-verification result, when the address stage ran. */
+  address?: AddressResultData;
+  /** What a failed address does, from the workflow's address config. */
+  addressOnFail?: AddressOnFail;
 }
 /** Normalisation of gathered provider results into engine/webhook shapes. */
 declare class Normalize {

package/dist/normalize.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize.d.mts","names":[],"sources":["../src/normalize.ts"],"mappings":";;;;;;AAQA;UAAiB,cAAA;EACf,oBAAA;EACA,GAAA,EAAK,aAAA;EACL,QAAA,EAAU,kBAAA;EACV,SAAA,EAAW,mBAAA;AAAA;;cAIA,SAAA;EANX;;;;;;;AAE8B;AAIhC;EANE,OAgBO,eAAA,CAAgB,OAAA,EAAS,cAAA,EAAgB,GAAA,EAAK,WAAA,GAAc,IAAA,GAAO,aAAA;;;;;;;;;SA2BnE,eAAA,CAAgB,OAAA,EAAS,cAAA,EAAgB,GAAA,EAAK,WAAA,GAAc,IAAA,GAAO,aAAA;AAAA"}
+{"version":3,"file":"normalize.d.mts","names":[],"sources":["../src/normalize.ts"],"mappings":";;;;;;AAiBA;;UAAiB,cAAA;EACf,oBAAA;EACA,GAAA,EAAK,aAAA;EACL,QAAA,EAAU,kBAAA;EACV,SAAA,EAAW,mBAAA;EAIK;EAFhB,OAAA,GAAU,iBAAA;EAEmB;EAA7B,aAAA,GAAgB,aAAA;AAAA;;cAIL,SAAA;EATD;;;;;;;;AAKmB;EALnB,OAmBH,eAAA,CAAgB,OAAA,EAAS,cAAA,EAAgB,GAAA,EAAK,WAAA,GAAc,IAAA,GAAO,aAAA;EAVtD;;;;;;;;EAAA,OAyCb,eAAA,CAAgB,OAAA,EAAS,cAAA,EAAgB,GAAA,EAAK,WAAA,GAAc,IAAA,GAAO,aAAA;AAAA"}

package/dist/normalize.mjs

@@ -26,6 +26,14 @@ var Normalize = class {
 			faceMatch: {
 				passed: signals.faceMatch.passed,
 				similarityScore: signals.faceMatch.similarityScore
+			},
+			address: signals.address ? {
+				passed: signals.address.passed,
+				score: signals.address.score,
+				onFail: signals.addressOnFail
+			} : {
+				passed: true,
+				score: 1
 			}
 		};
 	}
@@ -51,7 +59,12 @@ var Normalize = class {
 			face_match: {
 				passed: signals.faceMatch.passed,
 				similarity_score: signals.faceMatch.similarityScore
-			}
+			},
+			...signals.address ? { address: {
+				passed: signals.address.passed,
+				score: signals.address.score,
+				methods: signals.address.methods.map((m) => m.method)
+			} } : {}
 		};
 	}
 };

package/dist/normalize.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"normalize.mjs","names":[],"sources":["../src/normalize.ts"],"sourcesContent":["import type { FaceMatchResultData, IsoDateTime, LivenessResultData, OcrResultData, WebhookChecks } from '@arkyc/types'\n\nimport type { DecisionInput } from './decision'\nimport { SessionRules } from './session'\n\n/**\n * The raw provider outputs gathered for a session, plus the document quality.\n */\nexport interface SessionSignals {\n  documentQualityScore: number\n  ocr: OcrResultData\n  liveness: LivenessResultData\n  faceMatch: FaceMatchResultData\n}\n\n/** Normalisation of gathered provider results into engine/webhook shapes. */\nexport class Normalize {\n  /**\n   * Normalise gathered provider results into the flat {@link DecisionInput} the\n   * decision engine consumes. Document expiry is derived from the OCR `expiryDate`\n   * field relative to `now`.\n   *\n   * @param signals\n   * @param now\n   * @returns\n   */\n  static toDecisionInput(signals: SessionSignals, now: IsoDateTime | Date): DecisionInput {\n    return {\n      document: {\n        qualityScore: signals.documentQualityScore,\n        ocrConfidence: signals.ocr.confidence,\n        expired: SessionRules.isDocumentExpired(signals.ocr.fields.expiryDate, now),\n      },\n      liveness: {\n        passed: signals.liveness.passed,\n        score: signals.liveness.score,\n        multipleFaces: signals.liveness.spoofSignals.multipleFaces === true,\n      },\n      faceMatch: {\n        passed: signals.faceMatch.passed,\n        similarityScore: signals.faceMatch.similarityScore,\n      },\n    }\n  }\n\n  /**\n   * Build the `checks` summary embedded in webhook payloads from the same\n   * gathered signals.\n   *\n   * @param signals\n   * @param now\n   * @returns\n   */\n  static toWebhookChecks(signals: SessionSignals, now: IsoDateTime | Date): WebhookChecks {\n    return {\n      document: {\n        quality_score: signals.documentQualityScore,\n        ocr_confidence: signals.ocr.confidence,\n        expired: SessionRules.isDocumentExpired(signals.ocr.fields.expiryDate, now),\n      },\n      liveness: {\n        passed: signals.liveness.passed,\n        score: signals.liveness.score,\n      },\n      face_match: {\n        passed: signals.faceMatch.passed,\n        similarity_score: signals.faceMatch.similarityScore,\n      },\n    }\n  }\n}\n"],"mappings":";;;AAgBA,IAAa,YAAb,MAAuB;;;;;;;;;;CAUrB,OAAO,gBAAgB,SAAyB,KAAwC;EACtF,OAAO;GACL,UAAU;IACR,cAAc,QAAQ;IACtB,eAAe,QAAQ,IAAI;IAC3B,SAAS,aAAa,kBAAkB,QAAQ,IAAI,OAAO,YAAY,GAAG;GAC5E;GACA,UAAU;IACR,QAAQ,QAAQ,SAAS;IACzB,OAAO,QAAQ,SAAS;IACxB,eAAe,QAAQ,SAAS,aAAa,kBAAkB;GACjE;GACA,WAAW;IACT,QAAQ,QAAQ,UAAU;IAC1B,iBAAiB,QAAQ,UAAU;GACrC;EACF;CACF;;;;;;;;;CAUA,OAAO,gBAAgB,SAAyB,KAAwC;EACtF,OAAO;GACL,UAAU;IACR,eAAe,QAAQ;IACvB,gBAAgB,QAAQ,IAAI;IAC5B,SAAS,aAAa,kBAAkB,QAAQ,IAAI,OAAO,YAAY,GAAG;GAC5E;GACA,UAAU;IACR,QAAQ,QAAQ,SAAS;IACzB,OAAO,QAAQ,SAAS;GAC1B;GACA,YAAY;IACV,QAAQ,QAAQ,UAAU;IAC1B,kBAAkB,QAAQ,UAAU;GACtC;EACF;CACF;AACF"}
+{"version":3,"file":"normalize.mjs","names":[],"sources":["../src/normalize.ts"],"sourcesContent":["import type {\n  AddressOnFail,\n  AddressResultData,\n  FaceMatchResultData,\n  IsoDateTime,\n  LivenessResultData,\n  OcrResultData,\n  WebhookChecks,\n} from '@arkyc/types'\n\nimport type { DecisionInput } from './decision'\nimport { SessionRules } from './session'\n\n/**\n * The raw provider outputs gathered for a session, plus the document quality.\n * `address` is only present when the (opt-in) address stage ran.\n */\nexport interface SessionSignals {\n  documentQualityScore: number\n  ocr: OcrResultData\n  liveness: LivenessResultData\n  faceMatch: FaceMatchResultData\n  /** Address-verification result, when the address stage ran. */\n  address?: AddressResultData\n  /** What a failed address does, from the workflow's address config. */\n  addressOnFail?: AddressOnFail\n}\n\n/** Normalisation of gathered provider results into engine/webhook shapes. */\nexport class Normalize {\n  /**\n   * Normalise gathered provider results into the flat {@link DecisionInput} the\n   * decision engine consumes. Document expiry is derived from the OCR `expiryDate`\n   * field relative to `now`.\n   *\n   * @param signals\n   * @param now\n   * @returns\n   */\n  static toDecisionInput(signals: SessionSignals, now: IsoDateTime | Date): DecisionInput {\n    return {\n      document: {\n        qualityScore: signals.documentQualityScore,\n        ocrConfidence: signals.ocr.confidence,\n        expired: SessionRules.isDocumentExpired(signals.ocr.fields.expiryDate, now),\n      },\n      liveness: {\n        passed: signals.liveness.passed,\n        score: signals.liveness.score,\n        multipleFaces: signals.liveness.spoofSignals.multipleFaces === true,\n      },\n      faceMatch: {\n        passed: signals.faceMatch.passed,\n        similarityScore: signals.faceMatch.similarityScore,\n      },\n      // Absent address stage passes through so it can't veto a decision.\n      address: signals.address\n        ? { passed: signals.address.passed, score: signals.address.score, onFail: signals.addressOnFail }\n        : { passed: true, score: 1 },\n    }\n  }\n\n  /**\n   * Build the `checks` summary embedded in webhook payloads from the same\n   * gathered signals.\n   *\n   * @param signals\n   * @param now\n   * @returns\n   */\n  static toWebhookChecks(signals: SessionSignals, now: IsoDateTime | Date): WebhookChecks {\n    return {\n      document: {\n        quality_score: signals.documentQualityScore,\n        ocr_confidence: signals.ocr.confidence,\n        expired: SessionRules.isDocumentExpired(signals.ocr.fields.expiryDate, now),\n      },\n      liveness: {\n        passed: signals.liveness.passed,\n        score: signals.liveness.score,\n      },\n      face_match: {\n        passed: signals.faceMatch.passed,\n        similarity_score: signals.faceMatch.similarityScore,\n      },\n      ...(signals.address\n        ? {\n            address: {\n              passed: signals.address.passed,\n              score: signals.address.score,\n              methods: signals.address.methods.map((m) => m.method),\n            },\n          }\n        : {}),\n    }\n  }\n}\n"],"mappings":";;;AA6BA,IAAa,YAAb,MAAuB;;;;;;;;;;CAUrB,OAAO,gBAAgB,SAAyB,KAAwC;EACtF,OAAO;GACL,UAAU;IACR,cAAc,QAAQ;IACtB,eAAe,QAAQ,IAAI;IAC3B,SAAS,aAAa,kBAAkB,QAAQ,IAAI,OAAO,YAAY,GAAG;GAC5E;GACA,UAAU;IACR,QAAQ,QAAQ,SAAS;IACzB,OAAO,QAAQ,SAAS;IACxB,eAAe,QAAQ,SAAS,aAAa,kBAAkB;GACjE;GACA,WAAW;IACT,QAAQ,QAAQ,UAAU;IAC1B,iBAAiB,QAAQ,UAAU;GACrC;GAEA,SAAS,QAAQ,UACb;IAAE,QAAQ,QAAQ,QAAQ;IAAQ,OAAO,QAAQ,QAAQ;IAAO,QAAQ,QAAQ;GAAc,IAC9F;IAAE,QAAQ;IAAM,OAAO;GAAE;EAC/B;CACF;;;;;;;;;CAUA,OAAO,gBAAgB,SAAyB,KAAwC;EACtF,OAAO;GACL,UAAU;IACR,eAAe,QAAQ;IACvB,gBAAgB,QAAQ,IAAI;IAC5B,SAAS,aAAa,kBAAkB,QAAQ,IAAI,OAAO,YAAY,GAAG;GAC5E;GACA,UAAU;IACR,QAAQ,QAAQ,SAAS;IACzB,OAAO,QAAQ,SAAS;GAC1B;GACA,YAAY;IACV,QAAQ,QAAQ,UAAU;IAC1B,kBAAkB,QAAQ,UAAU;GACtC;GACA,GAAI,QAAQ,UACR,EACE,SAAS;IACP,QAAQ,QAAQ,QAAQ;IACxB,OAAO,QAAQ,QAAQ;IACvB,SAAS,QAAQ,QAAQ,QAAQ,KAAK,MAAM,EAAE,MAAM;GACtD,EACF,IACA,CAAC;EACP;CACF;AACF"}

package/dist/risk.mjs

@@ -32,9 +32,10 @@ var Risk = class Risk {
 			input.document.qualityScore,
 			input.document.ocrConfidence,
 			input.liveness.score,
-			input.faceMatch.similarityScore
+			input.faceMatch.similarityScore,
+			input.address.score
 		].map(Risk.clamp01));
-		if (input.document.expired || !input.liveness.passed || !input.faceMatch.passed || input.liveness.multipleFaces === true) risk = Math.max(risk, .9);
+		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);
 		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    ].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\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;EAQzC,IAAI,OAAO,IAAI,KAPG;GAChB,MAAM,SAAS;GACf,MAAM,SAAS;GACf,MAAM,SAAS;GACf,MAAM,UAAU;EAClB,CAAC,CAAC,IAAI,KAAK,OAEiB,CAAC;EAQ7B,IALE,MAAM,SAAS,WACf,CAAC,MAAM,SAAS,UAChB,CAAC,MAAM,UAAU,UACjB,MAAM,SAAS,kBAAkB,MAGjC,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.\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"}

package/dist/status.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.mts","names":[],"sources":["../src/status.ts"],"mappings":";;;;;AAKA;cAAa,4BAAA,SAAqC,KAAA;EAAA,SAE9B,IAAA,EAAM,kBAAA;EAAA,SACN,EAAA,EAAI,kBAAA;cADJ,IAAA,EAAM,kBAAA,EACN,EAAA,EAAI,kBAAA;AAAA;;;;cAUX,aAAA;EAbqC;;;;;;;;;;EAAA,gBAwBhC,WAAA,EAAa,QAAA,CAAS,MAAA,CAAO,kBAAA,WAA6B,kBAAA;EArBlC;EAAA,gBAqCxB,QAAA,WAAmB,kBAAA;EA3BX;;;;;;EAAA,OAmCjB,UAAA,CAAW,MAAA,EAAQ,kBAAA;EAAA;;;;;;;EAAA,OAWnB,aAAA,CAAc,IAAA,EAAM,kBAAA,EAAoB,EAAA,EAAI,kBAAA;EAnCnC;;;;;;;;EAAA,OA+CT,MAAA,CAAO,IAAA,EAAM,kBAAA,EAAoB,EAAA,EAAI,kBAAA,GAAqB,kBAAA;AAAA"}
+{"version":3,"file":"status.d.mts","names":[],"sources":["../src/status.ts"],"mappings":";;;;;AAKA;cAAa,4BAAA,SAAqC,KAAA;EAAA,SAE9B,IAAA,EAAM,kBAAA;EAAA,SACN,EAAA,EAAI,kBAAA;cADJ,IAAA,EAAM,kBAAA,EACN,EAAA,EAAI,kBAAA;AAAA;;;;cAUX,aAAA;EAbqC;;;;;;;;;;EAAA,gBAwBhC,WAAA,EAAa,QAAA,CAAS,MAAA,CAAO,kBAAA,WAA6B,kBAAA;EArBlC;EAAA,gBAwCxB,QAAA,WAAmB,kBAAA;EA9BX;;;;;;EAAA,OAsCjB,UAAA,CAAW,MAAA,EAAQ,kBAAA;EAAA;;;;;;;EAAA,OAWnB,aAAA,CAAc,IAAA,EAAM,kBAAA,EAAoB,EAAA,EAAI,kBAAA;EAtCnC;;;;;;;;EAAA,OAkDT,MAAA,CAAO,IAAA,EAAM,kBAAA,EAAoB,EAAA,EAAI,kBAAA,GAAqB,kBAAA;AAAA"}

package/dist/status.mjs

@@ -34,11 +34,19 @@ var StatusMachine = class StatusMachine {
 		],
 		started: [
 			"document_submitted",
+			"address_submitted",
 			"liveness_submitted",
 			"expired",
 			"cancelled"
 		],
 		document_submitted: [
+			"address_submitted",
+			"liveness_submitted",
+			"processing",
+			"expired",
+			"cancelled"
+		],
+		address_submitted: [
 			"liveness_submitted",
 			"processing",
 			"expired",
@@ -61,6 +69,7 @@ var StatusMachine = class StatusMachine {
 			"rejected",
 			"started",
 			"document_submitted",
+			"address_submitted",
 			"cancelled"
 		],
 		approved: [],

package/dist/status.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"status.mjs","names":[],"sources":["../src/status.ts"],"sourcesContent":["import type { VerificationStatus } from '@arkyc/types'\n\n/**\n * Thrown when an illegal status transition is attempted.\n */\nexport class InvalidStatusTransitionError extends Error {\n  constructor(\n    public readonly from: VerificationStatus,\n    public readonly to: VerificationStatus,\n  ) {\n    super(`Invalid verification status transition: ${from} → ${to}`)\n    this.name = 'InvalidStatusTransitionError'\n  }\n}\n\n/**\n * Verification session status-transition rules.\n */\nexport class StatusMachine {\n  /**\n   * Allowed status transitions for a verification session.\n   *\n   * The happy path is:\n   *   pending → started → document_submitted → liveness_submitted → processing\n   *   → (approved | rejected | requires_review)\n   *\n   * `requires_review` can move to a terminal decision (manual) or back for a\n   * retry. `expired` and `cancelled` are reachable from any non-terminal state.\n   */\n  static readonly TRANSITIONS: Readonly<Record<VerificationStatus, readonly VerificationStatus[]>> = {\n    pending: ['started', 'expired', 'cancelled'],\n    // `liveness_submitted` is reachable directly when a workflow runs liveness\n    // before (or instead of) document capture.\n    started: ['document_submitted', 'liveness_submitted', 'expired', 'cancelled'],\n    document_submitted: ['liveness_submitted', 'processing', 'expired', 'cancelled'],\n    liveness_submitted: ['processing', 'expired', 'cancelled'],\n    processing: ['approved', 'rejected', 'requires_review', 'expired', 'cancelled'],\n    requires_review: ['approved', 'rejected', 'started', 'document_submitted', 'cancelled'],\n    approved: [],\n    rejected: [],\n    expired: [],\n    cancelled: [],\n  }\n\n  /** Statuses from which no further transition is possible. */\n  static readonly TERMINAL: readonly VerificationStatus[] = ['approved', 'rejected', 'expired', 'cancelled']\n\n  /**\n   * Whether `status` is terminal (no further transitions allowed).\n   *\n   * @param status\n   * @returns\n   */\n  static isTerminal(status: VerificationStatus): boolean {\n    return StatusMachine.TERMINAL.includes(status)\n  }\n\n  /**\n   * Whether moving from `from` to `to` is a permitted transition.\n   *\n   * @param from\n   * @param to\n   * @returns\n   */\n  static canTransition(from: VerificationStatus, to: VerificationStatus): boolean {\n    return StatusMachine.TRANSITIONS[from].includes(to)\n  }\n\n  /**\n   * Assert that `from → to` is permitted, throwing {@link InvalidStatusTransitionError}\n   * otherwise. Returns `to` so it can be used inline.\n   *\n   * @param from\n   * @param to\n   * @returns\n   */\n  static assert(from: VerificationStatus, to: VerificationStatus): VerificationStatus {\n    if (!StatusMachine.canTransition(from, to)) {\n      throw new InvalidStatusTransitionError(from, to)\n    }\n    return to\n  }\n}\n"],"mappings":";;;;AAKA,IAAa,+BAAb,cAAkD,MAAM;CAEpC;CACA;CAFlB,YACE,MACA,IACA;EACA,MAAM,2CAA2C,KAAK,KAAK,IAAI;EAH/C,KAAA,OAAA;EACA,KAAA,KAAA;EAGhB,KAAK,OAAO;CACd;AACF;;;;AAKA,IAAa,gBAAb,MAAa,cAAc;;;;;;;;;;;CAWzB,OAAgB,cAAmF;EACjG,SAAS;GAAC;GAAW;GAAW;EAAW;EAG3C,SAAS;GAAC;GAAsB;GAAsB;GAAW;EAAW;EAC5E,oBAAoB;GAAC;GAAsB;GAAc;GAAW;EAAW;EAC/E,oBAAoB;GAAC;GAAc;GAAW;EAAW;EACzD,YAAY;GAAC;GAAY;GAAY;GAAmB;GAAW;EAAW;EAC9E,iBAAiB;GAAC;GAAY;GAAY;GAAW;GAAsB;EAAW;EACtF,UAAU,CAAC;EACX,UAAU,CAAC;EACX,SAAS,CAAC;EACV,WAAW,CAAC;CACd;;CAGA,OAAgB,WAA0C;EAAC;EAAY;EAAY;EAAW;CAAW;;;;;;;CAQzG,OAAO,WAAW,QAAqC;EACrD,OAAO,cAAc,SAAS,SAAS,MAAM;CAC/C;;;;;;;;CASA,OAAO,cAAc,MAA0B,IAAiC;EAC9E,OAAO,cAAc,YAAY,KAAK,CAAC,SAAS,EAAE;CACpD;;;;;;;;;CAUA,OAAO,OAAO,MAA0B,IAA4C;EAClF,IAAI,CAAC,cAAc,cAAc,MAAM,EAAE,GACvC,MAAM,IAAI,6BAA6B,MAAM,EAAE;EAEjD,OAAO;CACT;AACF"}
+{"version":3,"file":"status.mjs","names":[],"sources":["../src/status.ts"],"sourcesContent":["import type { VerificationStatus } from '@arkyc/types'\n\n/**\n * Thrown when an illegal status transition is attempted.\n */\nexport class InvalidStatusTransitionError extends Error {\n  constructor(\n    public readonly from: VerificationStatus,\n    public readonly to: VerificationStatus,\n  ) {\n    super(`Invalid verification status transition: ${from} → ${to}`)\n    this.name = 'InvalidStatusTransitionError'\n  }\n}\n\n/**\n * Verification session status-transition rules.\n */\nexport class StatusMachine {\n  /**\n   * Allowed status transitions for a verification session.\n   *\n   * The happy path is:\n   *   pending → started → document_submitted → liveness_submitted → processing\n   *   → (approved | rejected | requires_review)\n   *\n   * `requires_review` can move to a terminal decision (manual) or back for a\n   * retry. `expired` and `cancelled` are reachable from any non-terminal state.\n   */\n  static readonly TRANSITIONS: Readonly<Record<VerificationStatus, readonly VerificationStatus[]>> = {\n    pending: ['started', 'expired', 'cancelled'],\n    // Submit stages (`document`, `address`, `liveness`) are reorderable per\n    // workflow, so a submit status can be reached directly from `started` and\n    // flows forward into the next enabled submit stage or straight to `processing`.\n    started: ['document_submitted', 'address_submitted', 'liveness_submitted', 'expired', 'cancelled'],\n    document_submitted: ['address_submitted', 'liveness_submitted', 'processing', 'expired', 'cancelled'],\n    // `address` is the opt-in stage — between document and liveness in canonical order.\n    address_submitted: ['liveness_submitted', 'processing', 'expired', 'cancelled'],\n    liveness_submitted: ['processing', 'expired', 'cancelled'],\n    processing: ['approved', 'rejected', 'requires_review', 'expired', 'cancelled'],\n    requires_review: ['approved', 'rejected', 'started', 'document_submitted', 'address_submitted', 'cancelled'],\n    approved: [],\n    rejected: [],\n    expired: [],\n    cancelled: [],\n  }\n\n  /** Statuses from which no further transition is possible. */\n  static readonly TERMINAL: readonly VerificationStatus[] = ['approved', 'rejected', 'expired', 'cancelled']\n\n  /**\n   * Whether `status` is terminal (no further transitions allowed).\n   *\n   * @param status\n   * @returns\n   */\n  static isTerminal(status: VerificationStatus): boolean {\n    return StatusMachine.TERMINAL.includes(status)\n  }\n\n  /**\n   * Whether moving from `from` to `to` is a permitted transition.\n   *\n   * @param from\n   * @param to\n   * @returns\n   */\n  static canTransition(from: VerificationStatus, to: VerificationStatus): boolean {\n    return StatusMachine.TRANSITIONS[from].includes(to)\n  }\n\n  /**\n   * Assert that `from → to` is permitted, throwing {@link InvalidStatusTransitionError}\n   * otherwise. Returns `to` so it can be used inline.\n   *\n   * @param from\n   * @param to\n   * @returns\n   */\n  static assert(from: VerificationStatus, to: VerificationStatus): VerificationStatus {\n    if (!StatusMachine.canTransition(from, to)) {\n      throw new InvalidStatusTransitionError(from, to)\n    }\n    return to\n  }\n}\n"],"mappings":";;;;AAKA,IAAa,+BAAb,cAAkD,MAAM;CAEpC;CACA;CAFlB,YACE,MACA,IACA;EACA,MAAM,2CAA2C,KAAK,KAAK,IAAI;EAH/C,KAAA,OAAA;EACA,KAAA,KAAA;EAGhB,KAAK,OAAO;CACd;AACF;;;;AAKA,IAAa,gBAAb,MAAa,cAAc;;;;;;;;;;;CAWzB,OAAgB,cAAmF;EACjG,SAAS;GAAC;GAAW;GAAW;EAAW;EAI3C,SAAS;GAAC;GAAsB;GAAqB;GAAsB;GAAW;EAAW;EACjG,oBAAoB;GAAC;GAAqB;GAAsB;GAAc;GAAW;EAAW;EAEpG,mBAAmB;GAAC;GAAsB;GAAc;GAAW;EAAW;EAC9E,oBAAoB;GAAC;GAAc;GAAW;EAAW;EACzD,YAAY;GAAC;GAAY;GAAY;GAAmB;GAAW;EAAW;EAC9E,iBAAiB;GAAC;GAAY;GAAY;GAAW;GAAsB;GAAqB;EAAW;EAC3G,UAAU,CAAC;EACX,UAAU,CAAC;EACX,SAAS,CAAC;EACV,WAAW,CAAC;CACd;;CAGA,OAAgB,WAA0C;EAAC;EAAY;EAAY;EAAW;CAAW;;;;;;;CAQzG,OAAO,WAAW,QAAqC;EACrD,OAAO,cAAc,SAAS,SAAS,MAAM;CAC/C;;;;;;;;CASA,OAAO,cAAc,MAA0B,IAAiC;EAC9E,OAAO,cAAc,YAAY,KAAK,CAAC,SAAS,EAAE;CACpD;;;;;;;;;CAUA,OAAO,OAAO,MAA0B,IAA4C;EAClF,IAAI,CAAC,cAAc,cAAc,MAAM,EAAE,GACvC,MAAM,IAAI,6BAA6B,MAAM,EAAE;EAEjD,OAAO;CACT;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;EAaC;;;;;;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;EAcC;;;;;;EAAA,OAApB,OAAA,CAAQ,SAAA,GAAY,OAAA,CAAQ,sBAAA,IAA0B,sBAAA;AAAA"}

package/dist/thresholds.mjs

@@ -9,7 +9,8 @@ var Thresholds = class Thresholds {
 		documentQualityThreshold: .75,
 		ocrConfidenceThreshold: .8,
 		livenessThreshold: .85,
-		faceMatchThreshold: .75
+		faceMatchThreshold: .75,
+		addressThreshold: .6
 	};
 	/**
 	* 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  }\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;CACtB;;;;;;;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 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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkyc/core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Decision engine, status transitions, and scoring logic",
   "license": "MIT",
   "type": "module",
@@ -17,7 +17,7 @@
     "dist"
   ],
   "dependencies": {
-    "@arkyc/types": "^1.1.0"
+    "@arkyc/types": "^1.2.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",