@arkyc/core 1.0.0

package/dist/context.d.mts

@@ -0,0 +1,48 @@
+import { Id, OrganizationScoped } from "@arkyc/types";
+
+//#region src/context.d.ts
+/** Identifies the organization + project a request or entity belongs to. */
+interface OrganizationProjectContext {
+  organizationId: Id;
+  projectId: Id;
+}
+/**
+ * Thrown when an entity is accessed outside its organization/project scope.
+ */
+declare class OrganizationScopeError extends Error {
+  constructor(message?: string);
+}
+/** Organization/project scoping and storage-path helpers. */
+declare class OrganizationContext {
+  /**
+   * Whether `entity` belongs to the given organization.
+   *
+   * @param entity
+   * @param organizationId
+   * @returns
+   */
+  static belongsTo(entity: OrganizationScoped, organizationId: Id): boolean;
+  /**
+   * Assert that `entity` belongs to `organizationId`, throwing {@link OrganizationScopeError}
+   * otherwise. Returns the entity (narrowed) for inline use.
+   *
+   * @param entity
+   * @param organizationId
+   * @returns
+   */
+  static assertScope<T extends OrganizationScoped>(entity: T, organizationId: Id): T;
+  /**
+   * Build the canonical, organization/project-scoped storage key for a session object.
+   *
+   * e.g. `organizations/t1/projects/p1/sessions/s1/documents/front.jpg`
+   *
+   * @param ctx
+   * @param sessionId
+   * @param parts
+   * @returns
+   */
+  static storagePath(ctx: OrganizationProjectContext, sessionId: Id, ...parts: string[]): string;
+}
+//#endregion
+export { OrganizationContext, OrganizationProjectContext, OrganizationScopeError };
+//# sourceMappingURL=context.d.mts.map

package/dist/context.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.mts","names":[],"sources":["../src/context.ts"],"mappings":";;;;UAGiB,0BAAA;EACf,cAAA,EAAgB,EAAA;EAChB,SAAA,EAAW,EAAE;AAAA;;;;cAMF,sBAAA,SAA+B,KAAK;cACnC,OAAA;AAAA;AAPC;AAAA,cAcF,mBAAA;EARuB;;;;;;;EAAA,OAgB3B,SAAA,CAAU,MAAA,EAAQ,kBAAA,EAAoB,cAAA,EAAgB,EAAA;EARlD;;;;;;;;EAAA,OAoBJ,WAAA,WAAsB,kBAAA,EAAoB,MAAA,EAAQ,CAAA,EAAG,cAAA,EAAgB,EAAA,GAAK,CAAA;EAiBzD;;;;;;;;;;EAAA,OAAjB,WAAA,CAAY,GAAA,EAAK,0BAAA,EAA4B,SAAA,EAAW,EAAA,KAAO,KAAA;AAAA"}

package/dist/context.mjs

@@ -0,0 +1,60 @@
+//#region src/context.ts
+/**
+* Thrown when an entity is accessed outside its organization/project scope.
+*/
+var OrganizationScopeError = class extends Error {
+	constructor(message = "Entity is outside the active organization scope") {
+		super(message);
+		this.name = "OrganizationScopeError";
+	}
+};
+/** Organization/project scoping and storage-path helpers. */
+var OrganizationContext = class OrganizationContext {
+	/**
+	* Whether `entity` belongs to the given organization.
+	*
+	* @param entity
+	* @param organizationId
+	* @returns
+	*/
+	static belongsTo(entity, organizationId) {
+		return entity.organization_id === organizationId;
+	}
+	/**
+	* Assert that `entity` belongs to `organizationId`, throwing {@link OrganizationScopeError}
+	* otherwise. Returns the entity (narrowed) for inline use.
+	*
+	* @param entity
+	* @param organizationId
+	* @returns
+	*/
+	static assertScope(entity, organizationId) {
+		if (!OrganizationContext.belongsTo(entity, organizationId)) throw new OrganizationScopeError();
+		return entity;
+	}
+	/**
+	* Build the canonical, organization/project-scoped storage key for a session object.
+	*
+	* e.g. `organizations/t1/projects/p1/sessions/s1/documents/front.jpg`
+	*
+	* @param ctx
+	* @param sessionId
+	* @param parts
+	* @returns
+	*/
+	static storagePath(ctx, sessionId, ...parts) {
+		return [
+			"organizations",
+			ctx.organizationId,
+			"projects",
+			ctx.projectId,
+			"sessions",
+			sessionId,
+			...parts
+		].join("/");
+	}
+};
+//#endregion
+export { OrganizationContext, OrganizationScopeError };
+
+//# sourceMappingURL=context.mjs.map

package/dist/context.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.mjs","names":[],"sources":["../src/context.ts"],"sourcesContent":["import type { Id, OrganizationScoped } from '@arkyc/types'\n\n/** Identifies the organization + project a request or entity belongs to. */\nexport interface OrganizationProjectContext {\n  organizationId: Id\n  projectId: Id\n}\n\n/**\n * Thrown when an entity is accessed outside its organization/project scope.\n */\nexport class OrganizationScopeError extends Error {\n  constructor(message = 'Entity is outside the active organization scope') {\n    super(message)\n    this.name = 'OrganizationScopeError'\n  }\n}\n\n/** Organization/project scoping and storage-path helpers. */\nexport class OrganizationContext {\n  /**\n   * Whether `entity` belongs to the given organization.\n   *\n   * @param entity\n   * @param organizationId\n   * @returns\n   */\n  static belongsTo(entity: OrganizationScoped, organizationId: Id): boolean {\n    return entity.organization_id === organizationId\n  }\n\n  /**\n   * Assert that `entity` belongs to `organizationId`, throwing {@link OrganizationScopeError}\n   * otherwise. Returns the entity (narrowed) for inline use.\n   *\n   * @param entity\n   * @param organizationId\n   * @returns\n   */\n  static assertScope<T extends OrganizationScoped>(entity: T, organizationId: Id): T {\n    if (!OrganizationContext.belongsTo(entity, organizationId)) {\n      throw new OrganizationScopeError()\n    }\n    return entity\n  }\n\n  /**\n   * Build the canonical, organization/project-scoped storage key for a session object.\n   *\n   * e.g. `organizations/t1/projects/p1/sessions/s1/documents/front.jpg`\n   *\n   * @param ctx\n   * @param sessionId\n   * @param parts\n   * @returns\n   */\n  static storagePath(ctx: OrganizationProjectContext, sessionId: Id, ...parts: string[]): string {\n    const segments = ['organizations', ctx.organizationId, 'projects', ctx.projectId, 'sessions', sessionId, ...parts]\n    return segments.join('/')\n  }\n}\n"],"mappings":";;;;AAWA,IAAa,yBAAb,cAA4C,MAAM;CAChD,YAAY,UAAU,mDAAmD;EACvE,MAAM,OAAO;EACb,KAAK,OAAO;CACd;AACF;;AAGA,IAAa,sBAAb,MAAa,oBAAoB;;;;;;;;CAQ/B,OAAO,UAAU,QAA4B,gBAA6B;EACxE,OAAO,OAAO,oBAAoB;CACpC;;;;;;;;;CAUA,OAAO,YAA0C,QAAW,gBAAuB;EACjF,IAAI,CAAC,oBAAoB,UAAU,QAAQ,cAAc,GACvD,MAAM,IAAI,uBAAuB;EAEnC,OAAO;CACT;;;;;;;;;;;CAYA,OAAO,YAAY,KAAiC,WAAe,GAAG,OAAyB;EAE7F,OAAO;GADW;GAAiB,IAAI;GAAgB;GAAY,IAAI;GAAW;GAAY;GAAW,GAAG;EAC9F,CAAC,CAAC,KAAK,GAAG;CAC1B;AACF"}

package/dist/decision.d.mts

@@ -0,0 +1,61 @@
+import { DecisionReason, VerificationDecision, VerificationThresholds } from "@arkyc/types";
+
+//#region src/decision.d.ts
+/** Document signals fed to the decision engine. */
+interface DecisionDocumentInput {
+  /** Document image quality in [0, 1]. */
+  qualityScore: number;
+  /** OCR extraction confidence in [0, 1]. */
+  ocrConfidence: number;
+  /** Whether the document is past its expiry date. */
+  expired: boolean;
+}
+/** Liveness signals fed to the decision engine. */
+interface DecisionLivenessInput {
+  passed: boolean;
+  /** Liveness confidence in [0, 1]. */
+  score: number;
+  /** Whether more than one face was detected in the selfie/liveness frame. */
+  multipleFaces?: boolean;
+}
+/** Face-match signals fed to the decision engine. */
+interface DecisionFaceMatchInput {
+  passed: boolean;
+  /** Similarity between document portrait and selfie in [0, 1]. */
+  similarityScore: number;
+}
+/** The complete set of signals the decision engine evaluates. */
+interface DecisionInput {
+  document: DecisionDocumentInput;
+  liveness: DecisionLivenessInput;
+  faceMatch: DecisionFaceMatchInput;
+}
+/** The decision engine's verdict for a session. */
+interface DecisionResult {
+  decision: VerificationDecision;
+  reason: DecisionReason;
+  /** Aggregate risk score in [0, 1] (higher = riskier). */
+  riskScore: number;
+}
+/** Deterministic verification decision engine. */
+declare class DecisionEngine {
+  /**
+   * Decide a verification outcome from the gathered signals.
+   *
+   * Hard failures reject outright; borderline/low-confidence signals route to
+   * manual review; everything clearing its threshold is auto-approved. Checks are
+   * evaluated in a fixed priority order so the result is deterministic.
+   *
+   * Reject precedence:  expired → liveness failed → face-match failed
+   * Review precedence:   multiple faces → low quality → low OCR
+   *                       → low liveness → low face-match
+   *
+   * @param input
+   * @param thresholds
+   * @returns
+   */
+  static decide(input: DecisionInput, thresholds?: Partial<VerificationThresholds>): DecisionResult;
+}
+//#endregion
+export { DecisionDocumentInput, DecisionEngine, DecisionFaceMatchInput, DecisionInput, DecisionLivenessInput, DecisionResult };
+//# sourceMappingURL=decision.d.mts.map

package/dist/decision.d.mts.map

@@ -0,0 +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"}

package/dist/decision.mjs

@@ -0,0 +1,43 @@
+import { Thresholds } from "./thresholds.mjs";
+import { Risk } from "./risk.mjs";
+//#region src/decision.ts
+/** Deterministic verification decision engine. */
+var DecisionEngine = class {
+	/**
+	* Decide a verification outcome from the gathered signals.
+	*
+	* Hard failures reject outright; borderline/low-confidence signals route to
+	* manual review; everything clearing its threshold is auto-approved. Checks are
+	* evaluated in a fixed priority order so the result is deterministic.
+	*
+	* Reject precedence:  expired → liveness failed → face-match failed
+	* Review precedence:   multiple faces → low quality → low OCR
+	*                       → low liveness → low face-match
+	*
+	* @param input
+	* @param thresholds
+	* @returns
+	*/
+	static decide(input, thresholds) {
+		const t = Thresholds.resolve(thresholds);
+		const riskScore = Risk.score(input);
+		const verdict = (decision, reason) => ({
+			decision,
+			reason,
+			riskScore
+		});
+		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.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");
+		return verdict("approved", "AUTO_APPROVED");
+	}
+};
+//#endregion
+export { DecisionEngine };
+
+//# sourceMappingURL=decision.mjs.map

package/dist/decision.mjs.map

@@ -0,0 +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"}

package/dist/index.d.mts

@@ -0,0 +1,8 @@
+import { Thresholds } from "./thresholds.mjs";
+import { InvalidStatusTransitionError, StatusMachine } from "./status.mjs";
+import { 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 };

package/dist/index.mjs

@@ -0,0 +1,8 @@
+import { Thresholds } from "./thresholds.mjs";
+import { InvalidStatusTransitionError, StatusMachine } from "./status.mjs";
+import { Risk } from "./risk.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 };

package/dist/normalize.d.mts

@@ -0,0 +1,38 @@
+import { DecisionInput } from "./decision.mjs";
+import { 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.
+ */
+interface SessionSignals {
+  documentQualityScore: number;
+  ocr: OcrResultData;
+  liveness: LivenessResultData;
+  faceMatch: FaceMatchResultData;
+}
+/** Normalisation of gathered provider results into engine/webhook shapes. */
+declare class Normalize {
+  /**
+   * Normalise gathered provider results into the flat {@link DecisionInput} the
+   * decision engine consumes. Document expiry is derived from the OCR `expiryDate`
+   * field relative to `now`.
+   *
+   * @param signals
+   * @param now
+   * @returns
+   */
+  static toDecisionInput(signals: SessionSignals, now: IsoDateTime | Date): DecisionInput;
+  /**
+   * Build the `checks` summary embedded in webhook payloads from the same
+   * gathered signals.
+   *
+   * @param signals
+   * @param now
+   * @returns
+   */
+  static toWebhookChecks(signals: SessionSignals, now: IsoDateTime | Date): WebhookChecks;
+}
+//#endregion
+export { Normalize, SessionSignals };
+//# sourceMappingURL=normalize.d.mts.map

package/dist/normalize.d.mts.map

@@ -0,0 +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"}

package/dist/normalize.mjs

@@ -0,0 +1,61 @@
+import { SessionRules } from "./session.mjs";
+//#region src/normalize.ts
+/** Normalisation of gathered provider results into engine/webhook shapes. */
+var Normalize = class {
+	/**
+	* Normalise gathered provider results into the flat {@link DecisionInput} the
+	* decision engine consumes. Document expiry is derived from the OCR `expiryDate`
+	* field relative to `now`.
+	*
+	* @param signals
+	* @param now
+	* @returns
+	*/
+	static toDecisionInput(signals, now) {
+		return {
+			document: {
+				qualityScore: signals.documentQualityScore,
+				ocrConfidence: signals.ocr.confidence,
+				expired: SessionRules.isDocumentExpired(signals.ocr.fields.expiryDate, now)
+			},
+			liveness: {
+				passed: signals.liveness.passed,
+				score: signals.liveness.score,
+				multipleFaces: signals.liveness.spoofSignals.multipleFaces === true
+			},
+			faceMatch: {
+				passed: signals.faceMatch.passed,
+				similarityScore: signals.faceMatch.similarityScore
+			}
+		};
+	}
+	/**
+	* Build the `checks` summary embedded in webhook payloads from the same
+	* gathered signals.
+	*
+	* @param signals
+	* @param now
+	* @returns
+	*/
+	static toWebhookChecks(signals, now) {
+		return {
+			document: {
+				quality_score: signals.documentQualityScore,
+				ocr_confidence: signals.ocr.confidence,
+				expired: SessionRules.isDocumentExpired(signals.ocr.fields.expiryDate, now)
+			},
+			liveness: {
+				passed: signals.liveness.passed,
+				score: signals.liveness.score
+			},
+			face_match: {
+				passed: signals.faceMatch.passed,
+				similarity_score: signals.faceMatch.similarityScore
+			}
+		};
+	}
+};
+//#endregion
+export { Normalize };
+
+//# sourceMappingURL=normalize.mjs.map

package/dist/normalize.mjs.map

@@ -0,0 +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"}

package/dist/risk.d.mts

@@ -0,0 +1,28 @@
+import { DecisionInput } from "./decision.mjs";
+
+//#region src/risk.d.ts
+/** Aggregate risk scoring for a verification session. */
+declare class Risk {
+  /**
+   * Clamp a number into the [0, 1] range.
+   *
+   * @param value
+   * @returns
+   */
+  static clamp01(value: number): number;
+  /**
+   * Compute an aggregate risk score in [0, 1] for a session (higher = riskier).
+   *
+   * 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.
+   *
+   * @param input
+   * @returns
+   */
+  static score(input: DecisionInput): number;
+}
+//#endregion
+export { Risk };
+//# sourceMappingURL=risk.d.mts.map

package/dist/risk.d.mts.map

@@ -0,0 +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"}

package/dist/risk.mjs

@@ -0,0 +1,44 @@
+//#region src/risk.ts
+/** Average of a list of numbers; 0 for an empty list. */
+function mean(values) {
+	if (values.length === 0) return 0;
+	return values.reduce((sum, v) => sum + v, 0) / values.length;
+}
+/** Aggregate risk scoring for a verification session. */
+var Risk = class Risk {
+	/**
+	* Clamp a number into the [0, 1] range.
+	*
+	* @param value
+	* @returns
+	*/
+	static clamp01(value) {
+		if (Number.isNaN(value)) return 0;
+		return Math.min(1, Math.max(0, value));
+	}
+	/**
+	* Compute an aggregate risk score in [0, 1] for a session (higher = riskier).
+	*
+	* 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.
+	*
+	* @param input
+	* @returns
+	*/
+	static score(input) {
+		let risk = 1 - mean([
+			input.document.qualityScore,
+			input.document.ocrConfidence,
+			input.liveness.score,
+			input.faceMatch.similarityScore
+		].map(Risk.clamp01));
+		if (input.document.expired || !input.liveness.passed || !input.faceMatch.passed || input.liveness.multipleFaces === true) risk = Math.max(risk, .9);
+		return Risk.clamp01(risk);
+	}
+};
+//#endregion
+export { Risk };
+
+//# sourceMappingURL=risk.mjs.map

package/dist/risk.mjs.map

@@ -0,0 +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"}

package/dist/session.d.mts

@@ -0,0 +1,40 @@
+import { IsoDate, IsoDateTime, VerificationStatus } from "@arkyc/types";
+
+//#region src/session.d.ts
+/** Pure session/document expiry rules. */
+declare class SessionRules {
+  /**
+   * Whether a session has passed its `expires_at` instant.
+   *
+   * `now` is injected (not read from the clock) so this stays pure and testable.
+   *
+   * @param expiresAt
+   * @param now
+   * @returns
+   */
+  static isSessionExpired(expiresAt: IsoDateTime | Date, now: IsoDateTime | Date): boolean;
+  /**
+   * Whether a document is expired relative to `now`.
+   *
+   * Expiry is treated as end-of-day: a document expiring on `now`'s date is still
+   * valid that day. Returns `false` when no expiry date is known.
+   *
+   * @param expiryDate
+   * @param now
+   * @returns
+   */
+  static isDocumentExpired(expiryDate: IsoDate | null | undefined, now: IsoDateTime | Date): boolean;
+  /**
+   * Whether a session in `status` should be auto-expired given its `expires_at`.
+   * Terminal sessions are never re-expired.
+   *
+   * @param status
+   * @param expiresAt
+   * @param now
+   * @returns
+   */
+  static shouldExpire(status: VerificationStatus, expiresAt: IsoDateTime | Date, now: IsoDateTime | Date): boolean;
+}
+//#endregion
+export { SessionRules };
+//# sourceMappingURL=session.d.mts.map

package/dist/session.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.mts","names":[],"sources":["../src/session.ts"],"mappings":";;;;cAUa,YAAA;EAAA;;;;;;;;;EAAA,OAUJ,gBAAA,CAAiB,SAAA,EAAW,WAAA,GAAc,IAAA,EAAM,GAAA,EAAK,WAAA,GAAc,IAAA;EA8B9C;;;;;;;;;;EAAA,OAhBrB,iBAAA,CAAkB,UAAA,EAAY,OAAA,qBAA4B,GAAA,EAAK,WAAA,GAAc,IAAA;EAdxB;;;;;;;;;EAAA,OA8BrD,YAAA,CAAa,MAAA,EAAQ,kBAAA,EAAoB,SAAA,EAAW,WAAA,GAAc,IAAA,EAAM,GAAA,EAAK,WAAA,GAAc,IAAA;AAAA"}

package/dist/session.mjs

@@ -0,0 +1,54 @@
+import { StatusMachine } from "./status.mjs";
+//#region src/session.ts
+/** Coerce an ISO string or Date into epoch milliseconds. */
+function toMillis(value) {
+	return value instanceof Date ? value.getTime() : new Date(value).getTime();
+}
+/** Pure session/document expiry rules. */
+var SessionRules = class SessionRules {
+	/**
+	* Whether a session has passed its `expires_at` instant.
+	*
+	* `now` is injected (not read from the clock) so this stays pure and testable.
+	*
+	* @param expiresAt
+	* @param now
+	* @returns
+	*/
+	static isSessionExpired(expiresAt, now) {
+		return toMillis(now) >= toMillis(expiresAt);
+	}
+	/**
+	* Whether a document is expired relative to `now`.
+	*
+	* Expiry is treated as end-of-day: a document expiring on `now`'s date is still
+	* valid that day. Returns `false` when no expiry date is known.
+	*
+	* @param expiryDate
+	* @param now
+	* @returns
+	*/
+	static isDocumentExpired(expiryDate, now) {
+		if (!expiryDate) return false;
+		const expiryEndOfDay = (/* @__PURE__ */ new Date(`${expiryDate}T23:59:59.999Z`)).getTime();
+		if (Number.isNaN(expiryEndOfDay)) return false;
+		return toMillis(now) > expiryEndOfDay;
+	}
+	/**
+	* Whether a session in `status` should be auto-expired given its `expires_at`.
+	* Terminal sessions are never re-expired.
+	*
+	* @param status
+	* @param expiresAt
+	* @param now
+	* @returns
+	*/
+	static shouldExpire(status, expiresAt, now) {
+		if (StatusMachine.isTerminal(status)) return false;
+		return SessionRules.isSessionExpired(expiresAt, now);
+	}
+};
+//#endregion
+export { SessionRules };
+
+//# sourceMappingURL=session.mjs.map

package/dist/session.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.mjs","names":[],"sources":["../src/session.ts"],"sourcesContent":["import type { IsoDate, IsoDateTime, VerificationStatus } from '@arkyc/types'\n\nimport { StatusMachine } from './status'\n\n/** Coerce an ISO string or Date into epoch milliseconds. */\nfunction toMillis(value: IsoDateTime | IsoDate | Date): number {\n  return value instanceof Date ? value.getTime() : new Date(value).getTime()\n}\n\n/** Pure session/document expiry rules. */\nexport class SessionRules {\n  /**\n   * Whether a session has passed its `expires_at` instant.\n   *\n   * `now` is injected (not read from the clock) so this stays pure and testable.\n   *\n   * @param expiresAt\n   * @param now\n   * @returns\n   */\n  static isSessionExpired(expiresAt: IsoDateTime | Date, now: IsoDateTime | Date): boolean {\n    return toMillis(now) >= toMillis(expiresAt)\n  }\n\n  /**\n   * Whether a document is expired relative to `now`.\n   *\n   * Expiry is treated as end-of-day: a document expiring on `now`'s date is still\n   * valid that day. Returns `false` when no expiry date is known.\n   *\n   * @param expiryDate\n   * @param now\n   * @returns\n   */\n  static isDocumentExpired(expiryDate: IsoDate | null | undefined, now: IsoDateTime | Date): boolean {\n    if (!expiryDate) return false\n    const expiryEndOfDay = new Date(`${expiryDate}T23:59:59.999Z`).getTime()\n    if (Number.isNaN(expiryEndOfDay)) return false\n    return toMillis(now) > expiryEndOfDay\n  }\n\n  /**\n   * Whether a session in `status` should be auto-expired given its `expires_at`.\n   * Terminal sessions are never re-expired.\n   *\n   * @param status\n   * @param expiresAt\n   * @param now\n   * @returns\n   */\n  static shouldExpire(status: VerificationStatus, expiresAt: IsoDateTime | Date, now: IsoDateTime | Date): boolean {\n    if (StatusMachine.isTerminal(status)) return false\n    return SessionRules.isSessionExpired(expiresAt, now)\n  }\n}\n"],"mappings":";;;AAKA,SAAS,SAAS,OAA6C;CAC7D,OAAO,iBAAiB,OAAO,MAAM,QAAQ,IAAI,IAAI,KAAK,KAAK,CAAC,CAAC,QAAQ;AAC3E;;AAGA,IAAa,eAAb,MAAa,aAAa;;;;;;;;;;CAUxB,OAAO,iBAAiB,WAA+B,KAAkC;EACvF,OAAO,SAAS,GAAG,KAAK,SAAS,SAAS;CAC5C;;;;;;;;;;;CAYA,OAAO,kBAAkB,YAAwC,KAAkC;EACjG,IAAI,CAAC,YAAY,OAAO;EACxB,MAAM,kCAAiB,IAAI,KAAK,GAAG,WAAW,eAAe,EAAA,CAAE,QAAQ;EACvE,IAAI,OAAO,MAAM,cAAc,GAAG,OAAO;EACzC,OAAO,SAAS,GAAG,IAAI;CACzB;;;;;;;;;;CAWA,OAAO,aAAa,QAA4B,WAA+B,KAAkC;EAC/G,IAAI,cAAc,WAAW,MAAM,GAAG,OAAO;EAC7C,OAAO,aAAa,iBAAiB,WAAW,GAAG;CACrD;AACF"}

package/dist/status.d.mts

@@ -0,0 +1,56 @@
+import { VerificationStatus } from "@arkyc/types";
+
+//#region src/status.d.ts
+/**
+ * Thrown when an illegal status transition is attempted.
+ */
+declare class InvalidStatusTransitionError extends Error {
+  readonly from: VerificationStatus;
+  readonly to: VerificationStatus;
+  constructor(from: VerificationStatus, to: VerificationStatus);
+}
+/**
+ * Verification session status-transition rules.
+ */
+declare class StatusMachine {
+  /**
+   * Allowed status transitions for a verification session.
+   *
+   * The happy path is:
+   *   pending → started → document_submitted → liveness_submitted → processing
+   *   → (approved | rejected | requires_review)
+   *
+   * `requires_review` can move to a terminal decision (manual) or back for a
+   * retry. `expired` and `cancelled` are reachable from any non-terminal state.
+   */
+  static readonly TRANSITIONS: Readonly<Record<VerificationStatus, readonly VerificationStatus[]>>;
+  /** Statuses from which no further transition is possible. */
+  static readonly TERMINAL: readonly VerificationStatus[];
+  /**
+   * Whether `status` is terminal (no further transitions allowed).
+   *
+   * @param status
+   * @returns
+   */
+  static isTerminal(status: VerificationStatus): boolean;
+  /**
+   * Whether moving from `from` to `to` is a permitted transition.
+   *
+   * @param from
+   * @param to
+   * @returns
+   */
+  static canTransition(from: VerificationStatus, to: VerificationStatus): boolean;
+  /**
+   * Assert that `from → to` is permitted, throwing {@link InvalidStatusTransitionError}
+   * otherwise. Returns `to` so it can be used inline.
+   *
+   * @param from
+   * @param to
+   * @returns
+   */
+  static assert(from: VerificationStatus, to: VerificationStatus): VerificationStatus;
+}
+//#endregion
+export { InvalidStatusTransitionError, StatusMachine };
+//# sourceMappingURL=status.d.mts.map

package/dist/status.d.mts.map

@@ -0,0 +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"}

package/dist/status.mjs

@@ -0,0 +1,113 @@
+//#region src/status.ts
+/**
+* Thrown when an illegal status transition is attempted.
+*/
+var InvalidStatusTransitionError = class extends Error {
+	from;
+	to;
+	constructor(from, to) {
+		super(`Invalid verification status transition: ${from} → ${to}`);
+		this.from = from;
+		this.to = to;
+		this.name = "InvalidStatusTransitionError";
+	}
+};
+/**
+* Verification session status-transition rules.
+*/
+var StatusMachine = class StatusMachine {
+	/**
+	* Allowed status transitions for a verification session.
+	*
+	* The happy path is:
+	*   pending → started → document_submitted → liveness_submitted → processing
+	*   → (approved | rejected | requires_review)
+	*
+	* `requires_review` can move to a terminal decision (manual) or back for a
+	* retry. `expired` and `cancelled` are reachable from any non-terminal state.
+	*/
+	static TRANSITIONS = {
+		pending: [
+			"started",
+			"expired",
+			"cancelled"
+		],
+		started: [
+			"document_submitted",
+			"liveness_submitted",
+			"expired",
+			"cancelled"
+		],
+		document_submitted: [
+			"liveness_submitted",
+			"processing",
+			"expired",
+			"cancelled"
+		],
+		liveness_submitted: [
+			"processing",
+			"expired",
+			"cancelled"
+		],
+		processing: [
+			"approved",
+			"rejected",
+			"requires_review",
+			"expired",
+			"cancelled"
+		],
+		requires_review: [
+			"approved",
+			"rejected",
+			"started",
+			"document_submitted",
+			"cancelled"
+		],
+		approved: [],
+		rejected: [],
+		expired: [],
+		cancelled: []
+	};
+	/** Statuses from which no further transition is possible. */
+	static TERMINAL = [
+		"approved",
+		"rejected",
+		"expired",
+		"cancelled"
+	];
+	/**
+	* Whether `status` is terminal (no further transitions allowed).
+	*
+	* @param status
+	* @returns
+	*/
+	static isTerminal(status) {
+		return StatusMachine.TERMINAL.includes(status);
+	}
+	/**
+	* Whether moving from `from` to `to` is a permitted transition.
+	*
+	* @param from
+	* @param to
+	* @returns
+	*/
+	static canTransition(from, to) {
+		return StatusMachine.TRANSITIONS[from].includes(to);
+	}
+	/**
+	* Assert that `from → to` is permitted, throwing {@link InvalidStatusTransitionError}
+	* otherwise. Returns `to` so it can be used inline.
+	*
+	* @param from
+	* @param to
+	* @returns
+	*/
+	static assert(from, to) {
+		if (!StatusMachine.canTransition(from, to)) throw new InvalidStatusTransitionError(from, to);
+		return to;
+	}
+};
+//#endregion
+export { InvalidStatusTransitionError, StatusMachine };
+
+//# sourceMappingURL=status.mjs.map

package/dist/status.mjs.map

@@ -0,0 +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"}

package/dist/thresholds.d.mts

@@ -0,0 +1,21 @@
+import { VerificationThresholds } from "@arkyc/types";
+
+//#region src/thresholds.d.ts
+/** Verification threshold defaults and override resolution. */
+declare class Thresholds {
+  /**
+   * Platform default verification thresholds. Projects may override any subset
+   * via `ProjectSettings.thresholds`; {@link Thresholds.resolve} merges them.
+   */
+  static readonly DEFAULTS: VerificationThresholds;
+  /**
+   * Merge a partial set of project overrides over the platform defaults.
+   *
+   * @param overrides
+   * @returns
+   */
+  static resolve(overrides?: Partial<VerificationThresholds>): VerificationThresholds;
+}
+//#endregion
+export { Thresholds };
+//# sourceMappingURL=thresholds.d.mts.map

package/dist/thresholds.d.mts.map

@@ -0,0 +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"}

package/dist/thresholds.mjs

@@ -0,0 +1,30 @@
+//#region src/thresholds.ts
+/** Verification threshold defaults and override resolution. */
+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
+	};
+	/**
+	* Merge a partial set of project overrides over the platform defaults.
+	*
+	* @param overrides
+	* @returns
+	*/
+	static resolve(overrides) {
+		return {
+			...Thresholds.DEFAULTS,
+			...overrides ?? {}
+		};
+	}
+};
+//#endregion
+export { Thresholds };
+
+//# sourceMappingURL=thresholds.mjs.map

package/dist/thresholds.mjs.map

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@arkyc/core",
+  "version": "1.0.0",
+  "description": "Decision engine, status transitions, and scoring logic",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@arkyc/types": "^1.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "clean": "rm -rf dist"
+  }
+}